<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>MIDI Monitor Documentation</title>

    <!-- Bootstrap -->
    <link href="css/bootstrap.min.css" rel="stylesheet">

    <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
      <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
  </head>
  <body style="padding-top: 60px;">
    <div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
      <div class="container">
        <div class="navbar-header">
          <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
            <span class="sr-only">Toggle navigation</span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
            <span class="icon-bar"></span>
          </button>
          <a class="navbar-brand" href="http://www.snoize.com/MIDIMonitor/">MIDI Monitor</a>
        </div>
        <div class="collapse navbar-collapse">
          <ul class="nav navbar-nav">
            <li class="active"><a href="#">Documentation</a></li>
            <li><a href="#basics">Basics</a></li>
            <li><a href="#howto">How to use it</a></li>
            <li><a href="#preferences">Preferences</a></li>
            <li><a href="#advanced">Advanced</a></li>
            <li><a href="#uninstall">Uninstall</a></li>
            <li><a href="#contact">Contact</a></li>
          </ul>
        </div><!--/.nav-collapse -->
      </div>
    </div>

    <div class="container">

      <div class="row">
        <div class="col-xs-2">
          <img src="icon.png" class="img-responsive" alt="MIDI Monitor Icon">
        </div>
        <div class="col-xs-10">
          <div class="page-header">
            <h1><b>MIDI Monitor</b><br><small>Documentation</small></h1>
          </div>
        </div>
      </div>

      <div class="page-header">
        <h1 id="basics">Basics</h1>
      </div>

      <p><b>MIDI Monitor</b> is an app to display MIDI signals going in and out of your Mac. Musicians will find it handy for tracking down confusing MIDI problems, and programmers can use it to test MIDI drivers and applications.</p>
      <p>MIDI Monitor is FREE to download and use. The source code is available as Open Source, under the BSD license.</p>
      <p>MIDI Monitor requires a Mac with OS X 10.11 or later.</p>
      <p>Please check <a href="http://www.snoize.com/MIDIMonitor/">http://www.snoize.com/MIDIMonitor/</A> for news and updates.</p>

      <div class="page-header">
        <h1 id="howto">How to use it</h1>
      </div>

      <div class="row">
        <div class="col-md-6">
          <p>When you launch MIDI Monitor, it will automatically open a new document. The window shows you the MIDI messages that MIDI Monitor receives. There are also two sections, <b>Sources</b> and <b>Filter</b>, which start out hidden. Click the gray arrows to expand them.<p>

          <p>MIDI Monitor uses the standard Mac interface for dealing with documents. Just open, close, and save as usual. A MIDI Monitor document saves its settings and the displayed MIDI events.</p>
        </div>
        <div class="col-md-6">
          <img src="mainWindow.png" class="img-responsive" alt="Main Window">
        </div>
      </div>

      <h3>Events</h3>

      <p>The main part of the window shows the events that MIDI Monitor has received, in order from oldest to newest.</p>
        <dl class="dl-horizontal">
          <dt>Time</dt>
          <dd>When the event was received by the computer</dd>
          <dt>Source</dt>
          <dd>Where the event came from</dd>
          <dt>Message</dt>
          <dd>What kind of event happened: note on, note off, controller, etc.</dd>
          <dt>Chan</dt>
          <dd>What channel the event was on. Some types of events do not have a channel.</dd>
          <dt>Data</dt>
          <dd>The specific data in the event. The format depends on the type of event. Some events have no data.</dd>
        </dl>

      <p>To clear the list of events, press the <span class="label label-default">Clear</span> button, use the menu command <span class="label label-default">Events</span> &gt; <span class="label label-default">Clear Events</span>, or press <kbd>&#8984;K</kbd>.  To change the number of events that the list will remember, just change the number in the text field and press return.</p>

      <p>Some events contain more data than can be shown in one line: <b>System Exclusive</b> (or <b>SysEx</b>) events and <b>Invalid</b> events. To show the full contents of any event, double-click it, or use the menu command <span class="label label-default">Events</span> &gt; <span class="label label-default">Show Detailed Data</span>.</p>

      <h3>Sources</h3>

      <div class="row">
        <div class="col-md-6">
          <p>This section lets you choose the sources of MIDI events that this window listens to.</p>
        </div>
        <div class="col-md-6">
          <img src="sources.png" class="img-responsive" alt="Sources">
        </div>
      </div>

      <p>Sources come in three categories:</p>
      <dl>
        <dt>MIDI sources</dt>
        <dd>These are ordinary MIDI sources, such as the input ports on your MIDI interface. Other applications on the computer may also appear in the list, if they are running and can act as MIDI sources.
        </dd>

        <dt>Act as destination for other programs</dt>
        <dd>If you choose this, other applications will be able to send their output to this MIDI Monitor window, as though it was a MIDI output port.</dd>

        <dt>Spy on output to destinations</dt>
        <dd>Each MIDI destination on your computer is listed, including normal MIDI output ports, and applications which act as destinations. Selecting a destination lets you "spy" on the data that other apps send to that destination. This happens outside of the system's normal MIDI processing, so the application sending the data does not know that it is being spied upon.

          <p class="text-muted"><span class="glyphicon glyphicon-info-sign"></span>
            In order to do this, MIDI Monitor installs a MIDI driver in the Library/Audio/MIDI Drivers folder in your home folder. This driver does not have any effect on other applications, and does nothing when MIDI Monitor is not using it.
          </p>
        </dd>
      </dl>

      <h3>Filter</h3>

      <div class="row">
        <div class="col-md-6">
          <p>MIDI Monitor also provides a filter, so you can see only the events you are interested in.</p>
          <p>New windows start with all of the checkboxes checked, meaning that all messages are displayed. The large checkboxes control the filters for a whole category of messages; the small checkboxes each control the filter for one specific type of message. For "voice" messages, which include a channel number, you can also choose whether to listen to all channels or just one.</p>
        </div>
        <div class="col-md-6">
          <img src="filter.png" class="img-responsive" alt="Filter">
        </div>
      </div>

      <div class="page-header">
        <h1 id="preferences">Preferences</h1>
      </div>

      <p>The preferences window lets you change the way that MIDI Monitor displays values, as well as some other behavior. Changes in this window take effect immediately.</p>

      <div class="row">
        <div class="col-md-7">
          <h3>Display</h3>
          <h4>Time format</h4>
          <p>Controls how events' timestamps are displayed.</p>
          <dl>
            <dt>Clock time</dt>
            <dd>Shows the timestamp in terms of normal human time, to the nearest 0.001 second. This is the most useful setting.</dd>
            <dt>Host time</dt>
            <dd>Shows the timestamp in terms of the computer's internal timebase. Most people won't find this very useful, but programmers might.

              <dl class="dl-horizontal">
                <dt>Integer</dt>
                <dd>The time as returned by <code>AudioGetCurrentHostTime()</code> or <code>UpTime()</code>. This is an unsigned, 64-bit integer, which starts at 0 when the computer is started. This number will always increase at the same rate while the machine is running; however, one unit may represent different amounts of time on different machines, or different revisions of the operating system.</dd>

                <dt>Seconds</dt>
                <dd>The integer time divided by the number of ticks per second, as reported by <code>AudioGetHostClockFrequency()</code>. The value is shown to three decimal places.</dd>

                <dt>Nanoseconds</dt>
                <dd>The same as above, but with more digits displayed.</dd>
              </dl>
            </dd>
          </dl>

          <h4>Note format</h4>
          <p>Controls how MIDI Monitor displays the musical note in note-on and note-off events.</p>

          <dl class="dl-horizontal">
            <dt>Note (Middle C = C3)</dt>
            <dd>The name of the note in musical notation. Middle C (note 60) is displayed as C3, and the full range is from C-2 to G8. Yamaha uses this convention for naming notes, as do some (most?) other manufacturers.</dd>

            <dt>Note (Middle C = C4)</dt>
            <dd>As above, but displayed an octave higher. Middle C (note 60) is displayed as C4, and the full range is from C-1 to G9. Roland uses this convention.</dd>

            <dt>Decimal number</dt>
            <dd>The note number in base 10, from 0 to 127.</dd>

            <dt>Hexadecimal number</dt>
            <dd>The note number in base 16, from $00 to $7F.</dd>
          </dl>

          <h4>Controller format</h4>
          <p>The method of displaying the name or number of control events.</p>

          <dl class="dl-horizontal">
            <dt>Standard name</dt>
            <dd>The name of this controller as given in the MIDI standard. For example, controller 72 means &quot;Release Time&quot;. Controllers without standard names are displayed as decimal numbers. Some controllers come in pairs; one controller conveys the &quot;coarse&quot; value (or high byte) and the other conveys the &quot;fine&quot; value (or low byte).</dd>

            <dt>Decimal number</dt>
            <dd>The controller number in base 10, from 0 to 127.</dd>

            <dt>Hexadecimal number</dt>
            <dd>The controller number in base 16, from $00 to $7F.</dd>
          </dl>

          <h4>Data format</h4>
          <p>The method of displaying any other data in events.</p>
          <dl class="dl-horizontal">
            <dt>Decimal number</dt>
            <dd>The value in base 10. One byte values range from 0 to 127; signed two byte values range from -8192 to 8191.</dd>

            <dt>Hexadecimal number</dt>
            <dd>The value in base 16. One byte values range from $00 to $7F; two byte values range from $0000 to $3FFF, with $2000 as the &quot;center&quot; value.</dd>
          </dl>

          <h4>Program number (Decimal)</h4>
          <p>How to display program numbers in program change messages.</p>
          <dl class="dl-horizontal">
            <dt>1 - 128 (Standard)</dt>
            <dd>Most MIDI devices number their programs starting with 1.</dd>

            <dt>0 - 127 (Less common)</dt>
            <dd>Some MIDI devices number their programs starting with 0.</dd>
          </dl>

          <h4>Expert mode</h4>
          <p>Changes the display of all events. Intended for experts only.</p>
          <dl class="dl-horizontal">
            <dt>Data formatting</dt>
            <dd>Data is displayed as raw hexadecimal bytes, without any interpretation.</dd>

            <dt>Note off events</dt>
            <dd>According to the MIDI specification, a Note On event with velocity 0 is to be interpreted as the same as a Note Off event. Normally, MIDI Monitor shows &quot;Note Off&quot;, to avoid confusion. In expert mode, it will show &quot;Note On&quot;</dd>

            <dt>Zero timestamp</dt>
            <dd>When a program sends MIDI, it can provide a timestamp to schedule when the MIDI data should be sent, or zero which means &quot;send it immediately&quot;. Normally, when MIDI Monitor sees a zero timestamp, it will substitute a timestamp of when it received the data, to avoid confusion. (&quot;Why do the timestamps say 0? Is something broken?&quot;)  In expert mode, it will show &quot;0&quot;.</dd>
          </dl>
        </div>

        <div class="col-md-5">
          <img src="prefs1.png" class="img-responsive" alt="Display Preferences">
        </div>
      </div>

      <div class="row">
        <div class="col-md-7">
          <h3>Sources</h3>

          <dl>
            <dt>New windows will observe:</dt>
            <dd>When new windows are created, all of the sources in each of the checked categories will be selected.</dd>

            <dt>When new MIDI sources or destinations are added:</dt>
            <dd>Selects what to do when a new MIDI source or destination is added. (For example, when you plug in a MIDI interface, or start an app that acts as a virtual MIDI source or destination.)</dd>
          </dl>
        </div>
        <div class="col-md-5">
          <img src="prefs2.png" class="img-responsive" alt="Sources Preferences">
        </div>
      </div>

      <div class="row">
        <div class="col-md-7">
          <h3>Other</h3>

          <dl>
            <dt>Save SysEx</dt>
            <dd>This option lets you control how SysEx messages are saved to files. SysEx messages should always end with an EOX byte (hexadecimal F7). However, some devices do not follow this rule.
              <dl class="dl-horizontal">
                <dt>always with EOX byte ($F7)</dt>
                <dd>The file will end with an EOX byte, even if the message didn't have one when it was received. This is the default, and the most useful setting (especially if you want to use the SysEx file in another application).</dd>

                <dt>as it was received</dt>
                <dd>Saves the message exactly the same way as it was received, with or without the EOX byte.</dd>
              </dl>
            </dd>

            <dt>Ask to save when a changed window is closed</dt>
            <dd>When checked, MIDI Monitor will ask you to save a modified window when you close it, which is the standard Mac behavior. If you don't tend to save MIDI Monitor documents, this can get annoying, so uncheck this preference to turn off the warning.

              <p class="text-muted"><span class="glyphicon glyphicon-info-sign"></span>
                This preference depends on "Ask to keep changes when closing documents" in the General section of System Preferences.  If that is OFF (which it is, by default) then documents are automatically saved for you, and the MIDI Monitor preference only affects untitled documents. If the system preference is ON, then the MIDI Monitor preference affects all documents.
              </p>
            </dd>

            <dt>Automatically check for updates</dt>
            <dd>When checked, MIDI Monitor will periodically check if a newer version is available.</dd>

          </dl>
        </div>
        <div class="col-md-5">
          <img src="prefs3.png" class="img-responsive" alt="Other Preferences">
        </div>
      </div>

      <div class="page-header">
        <h1 id="advanced">Advanced Features</h1>
      </div>

      <div class="row">
        <div class="col-md-7">
          <h3>Detailed Event Data</h3>

          <p>To see the contents of an event, double-click it, or select it and use the menu command <span class="label label-default">Events</span> &gt; <span class="label label-default">Show Detailed Data</span>.</p>

          <p>The window shows information about the event, as well as a dump of the event's data in both hexadecimal and ASCII formats, which you can select and copy.</p>
          <p>System Exclusive events also display a &quot;Save As&quot; button which saves the data to a file.</p>

          <h3>Rescan MIDI</h3>
          <p>You can use the menu command <span class="label label-default">Special</span> &gt; <span class="label label-default">Rescan MIDI</span> to reinitialize the entire MIDI system and look for available devices. Generally you shouldn't need to do this, but I've included it as a convenience. The Audio MIDI Setup application has a &quot;Rescan MIDI&quot; button that does exactly the same thing. <br>(Developers: the menu command just calls CoreMIDI's <code>MIDIRestart()</code> function.)</p>

        </div>
        <div class="col-md-5">
          <img src="sysexWindow.png" class="img-responsive" alt="SysEx Event Data">
        </div>
      </div>

      <div class="page-header">
        <h1 id="uninstall">Uninstall</h1>
      </div>

      <div class="row">
        <div class="col-md-7">
          <h3>How to uninstall MIDI Monitor</h3>

          <ol>
            <li>Drag the <b>MIDI Monitor</b> application to the Trash</li>
            <li>In the Finder, select the menu item <span class="label label-default">Go</span> &gt; <span class="label label-default">Go to Folder…</span></li>
            <li>Type the following, then press Go:<br>
                <kbd>~/Library/Audio/MIDI Drivers</kbd></li>
            <li>In the window that appears, you should see <b>MIDI Monitor.plugin</b>.<br>
                Drag it to the Trash too.</li>
            <li>Go to this folder:<br>
                <kbd>~/Library/Preferences</kbd></li>
            <li>Select <b>com.snoize.MIDIMonitor.plist</b> and drag it to the Trash.</li>
            <li>Restart, just in case.</li>
          </ol>

         </div> 
      </div>


      <div class="page-header">
        <h1 id="contact">Contact</h1>
      </div>

      <p>Please send questions or comments to <a href="mailto:MIDIMonitor@snoize.com">MIDIMonitor@snoize.com</a>
      <br>If you find this app useful, if you encounter bugs, or if you have suggestions for improvement, I'd love to hear about it!</p>

      <div class="page-header">
        <h1>Acknowledgements</h1>
      </div>

      <P>MIDI Monitor includes software from:
      <ul>
      <li><a href="https://hexfiend.com/">Hex Fiend</a>
      </ul>

      <p>Hex Fiend license:
      <pre>Copyright (c) 2005-2016, Peter Ammon
* All rights reserved.
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
*     * Redistributions of source code must retain the above copyright
*       notice, this list of conditions and the following disclaimer.
*     * Redistributions in binary form must reproduce the above copyright
*       notice, this list of conditions and the following disclaimer in the
*       documentation and/or other materials provided with the distribution.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</pre>

    </div><!-- /.container -->


    <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
    <!-- Include all compiled plugins (below), or include individual files as needed -->
    <script src="js/bootstrap.min.js"></script>

  </body>
</html>
